.TH lpjml 1  "August 1, 2017" "version 4.0.002" "USER COMMANDS"
.SH NAME
lpj, lpjml \- Dynamic global vegetation model with managed land and river routing
.SH SYNOPSIS
.B lpjml
[\-h] [\-l] [\-v] [-vv] [-param] [-pp cmd] [-fpe] [-image host[:inport[,outport]]] [\-wait time] [\-output {write|gather|mpi2|socket=hostname[:port]}] [\-outpath \fIdir\fP]
[\-inpath \fIdir\fP] [\-restartpath \fIdir\fP]
[[\-Dmacro[=value]] [\-I\fIdir\fP] ...] [\fIfilename\fP]

.B lpj
[\-h] [\-l] [\-v] [-vv] [-param] [-pp cmd] [-fpe] [-image host[:inport[,outport]]] [\-wait time] [\-output {write|gather|mpi2|socket=hostname[:port]}] [\-outpath \fIdir\fP]
[\-inpath \fIdir\fP] [\-restartpath \fIdir\fP]
[[\-Dmacro[=value]] [\-I\fIdir\fP] ...] [\fIfilename\fP]
.SH DESCRIPTION
The model simulates vegetation dynamics, hydrology and soil 
organic matter dynamics on an area-averaged grid cell basis using
one-year time step. The name derives from the three locations \fBL\fPund-\fBP\fPotsdam-\fBJ\fPena but is no longer to be interpreted that way. Input parameters are monthly mean air
temperature, total precipitation and percentage of full sunshine,
annual atmospheric CO2 concentration and soil texture class. The
simulation for each grid cell begins from "bare ground",
requiring a "spin up" (under non-transient climate) of c. 5000
years to develop equilibrium vegetation and soil structure. A restart
file can be created to save compute time for the spin-up phase. If the Message Passing Interface (MPI) library is available a parallel version of the program is built. If -DIMAGE flag is set in \fIMakefile.inc\fP coupling the IMAGE model via the TDT library is enabled.
.SH OPTIONS
.TP
\-h
print a short help text
.TP
\-l
print the license file
.TP
\-v
print information about program version, operating system, compiler used, and compiler flags set.
.TP
\-vv
verbosely print the actual values during reading of the configuration files.
.TP
\-param
print LPJmL parameter for soils and PFTs.
.TP
\-pp cmd
set preprocessor program to cmd. Default is \fBcpp -P\fP.
.TP
\-fpe
enable floating point exceptions. A core file is generated in case of an arithmetic error. Option is only available if \fBlpjml\fP has been compiled with -DWITH_FPE flag.
.TP
\-image host[:inport[,outport]]
set host where IMAGE model is running. Default is localhost. inport and outport are the port numbers for ingoing and outgoing data. Default port numbers are 2225 and 2224, respectively. This option is only available for the IMAGE version of the code.
.TP
\-wait time
set time to wait for connection to IMAGE model. Time is measured in seconds. Default value is 10 sec. This option is only available for the IMAGE version of the code.
.TP
\-output {gather|mpi2|socket=hostname[:port]]}
use the given output method to write data to disk or to a output channel. Valid output methods are write,
gather, mpi2, and socket. The default output method for the MPI version is gather sending all output to the root task, while the default method is write for the sequential version of the code. Method mpi2 uses MPI-2 parallel file functions, while output method socket sends output data via a TCP/IP socket to a remote host hostname. Default port is 2222. \fBlpjliveview\fP is a program to display output variables on a X11 display at run time. The mpi2 and gather output methods are only valid for the MPI version of the code.  
.TP
\-outpath \fIdir\fP
set the output directory path. The path is added to the output filenames if they do not contain an absolute path.
.TP
\-inpath \fIdir\fP
set the input directory path. The path is added to the input filenames if they do not contain an absolute path.
.TP
\-restartpath \fIdir\fP
set the restart directory path. The path is added to the restart filenames if they do not contain an absolute path.
.TP
\-Dmacro[=value]
define macro for the preprocessor of the configuration file
.TP
\-I\fIdir\fP
define include directory for the preprocessor of the configuration file
.TP
.I filename
name of configuration file, default is \fIlpjml.js\fP for \fBlpjml\fP and \fIlpj.js\fP for \fBlpj\fP.
.SH EXAMPLES
.TP
Perform simulation with input from the /scratch file system:
.B lpjml
\-inpath /scratch/02/lpj
.PP
.TP
Perform simulation with output sent to host aix:
.B lpjml
\-output socket=aix
.PP
.TP
Start simulation from restart file with floating point exceptions enabled:
.B lpjml
\-DFROM_RESTART \-fpe lpjml.js
.PP
For running the MPI version of the program on more than one task the
.B lpjsubmit
script has to be used.
.SH ENVIRONMENT
.TP
LPJCONFIG
default LPJmL configuration filename
.TP
LPJPREP 
defines preprocessor command for LPJmL configuration file, default is \fBcpp -P\fP. Same as '-pp' option.
.TP
LPJROOT
defines the root directory for LPJmL. This directory is added to the
include directories of the preprocessor. Invoking \fBlpj_paths.sh\fP or \fBlpj_paths.csh\fP will set this
environment variable correctly.
.TP
LPJIMAGE
sets the host where IMAGE model is running. Same as '-image' option.
.TP
LPJWAITIMAGE
sets time to wait for connection to IMAGE model. Same as in '-wait' option.
.TP
LPJINPATH
path appended to the input filenames. Only done for filenames without absolute path. Same as '-inpath \fIdir\fP' option.
.TP
LPJOPTIONS     
runtime options for the preprocessor of LPJmL configuration files
.TP
LPJOUTPATH
path appended to the output filenames. Only done for filenames without absolute path. Same as '-outpath \fIdir\fP' option.
.TP
LPJRESTARTPATH
path appended to the restart filenames. Only done for filenames without absolute path. Same as '-restartpath \fIdir\fP' option.
.TP
LPJOUTPUT
default method for generating output files. Valid values
are mpi2, gather, and socket. Same as '-output method' option.

.SH EXIT STATUS
.B lpjml
and
.B lpj 
returns a zero exit status if the simulation finishes successfully.
Non zero is returned in case of failure.
.SH DIAGNOSTICS
On error the program prints the following message on stderr:

ERRORxxx: message, program terminated unsuccessfully

where xxx is the return code of the program. The following error codes are defined:
.TP
ERROR001 
Error reading configuration. Check syntax of configuration file. External error
.TP
ERROR002 
Error initializing input. Check whether all input files are present. External error
.TP
ERROR003 
Error initializing grid, check for missing input files. External error
.TP
ERROR004 
Invalid carbon balance. Internal error
.TP
ERROR005 
Invalid water balance. Internal error
.TP
ERROR006 
Negative discharge. Internal error
.TP
ERROR007 
Negative fire probability. Internal error.
.TP
ERROR008 
Negative soil moisture. Internal error
.TP
ERROR009 
Error allocating memory. Rerun parallel program on more MPI tasks to reduce memory per task. External error
.TP
ERROR010 
Negative stand fraction. Internal error.
.TP
ERROR011 
Stand fraction sum error. Can be caused by invalid restart file. External error
.TP
ERROR012 
List is empty in \fBdellistitem()\fP. Internal error.
.TP
ERROR013 
Index out of range in \fBdellistitem()\fP. Internal error
.TP
ERROR014
Error in \fBnewlanduse()\fP. Can be caused by invalid restart file. External error
.TP
ERROR015 
Invalid year in \fBgetco2()\fP. CO2 data file is too short. External error
.TP
ERROR016 
Crop fraction >1. Internal error.
.TP
ERROR017 
No natural stand for \fBdeforest()\fP. Internal error.
.TP
ERROR018 
Wrong cultivation type. Internal error.
.TP
ERROR019 
Floating point error occurred. Floating point exceptions will only be thrown if -fpe option is set. This is in particular useful if NaNs appear in the output files.  Internal error.
.TP
ERROR021 
PFT list is not empty in \fBsetaside()\fP. Internal error.
.TP
ERROR022 
Negative establishment rate. Internal error.
.TP
ERROR023
Output channel is broken. This error is only raised if '-output socket' option is set. It is usually caused by a premature end of the corresponding live view program. External error.
.TP
ERROR024
Error sending data to the IMAGE model. This error can only be raised if LPJmL is compiled with the -DIMAGE flag set in \fIMakefile.inc\fP. External error.
.TP
ERROR025
Error opening connection to IMAGE model. This error can only be raised if LPJmL is compiled with the -DIMAGE flag set in \fIMakefile.inc\fP. External error.
.TP
ERROR026
Not enough setaside stand created to put the reservoir. Internal error.
.TP
ERROR027
Forest left after deforestation. Internal error.
.TP
ERROR028
Outflow reservoir error. Internal error. 
.TP
ERROR029
Error in permafrost module. Internal error.
.TP
ERROR030
Error in global water balance. Internal error. 
.TP
ERROR031
Error in store climate function. 
.TP
ERROR032
No FMS coupler supported.
.TP
ERROR033
Error initializing soil temperature
.TP
ERROR034
Invalid radiation model. Internal error

.P
Internal errors will generate a core dump and have to be fixed by changes in the code. A "post-mortem" analysis can be made by calling 

\fBgdb\fP $LPJROOT/bin/lpjml core

It is recommended to compile the code without optimization and inlining making the inspection of the core file easier. Configure in $LPJROOT with

.nf
\fBconfigure.sh\fP -debug
\fBmake\fP clean
.B make
.fi

will do the job. If no core file is generated set the user limit for core files:

\fBulimit\fP -c unlimited

Some of these errors are only raised if the -DSAFE flag has been set in \fIMakefile.inc\fP. The flags set at compile time can be obtained by invoking \fBlpjml -v\fP. After the core file has been created a backtrace of the failed program can be obtained by calling

\fBbacktrace\fP

Without any arguments \fBlpjml\fP will be inspected and the call tree displayed using the core file in the working directory.

.SH AUTHORS

For authors and contributors see AUTHORS file

.SH COPYRIGHT

(C) Potsdam Institute for Climate Impact Research (PIK), see COPYRIGHT file

.SH SEE ALSO
lpjsubmit(1), lpjcheck(1), configure.sh(1), backtrace(1), cru2clm(1), txt2clm(1), grid2clm(1), cft2clm(1), lpjcat(1), lpjprint(1), printharvest(1), printclm(1), printheader(1), cat2bsq(1), output_bsq(1), lpj_paths.sh(1), lpj_paths.csh(1), lpjml.conf(5), lpj.conf(5), lpjml_image.conf(5), clm(5)
.TP
Contact: https://github.com/PIK-LPJmL/LPJmL /lpjml
